home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 April: Mac OS SDK / Dev.CD Apr 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / PInterfaces / AppleGuide.p < prev    next >
Encoding:
Text File  |  1998-08-17  |  13.2 KB  |  474 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        AppleGuide.p
  3.  
  4.      Contains:    Apple Guide Interfaces.
  5.  
  6.      Version:    Technology:    Mac OS 8
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    ©1994-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. }
  17. {$IFC UNDEFINED UsingIncludes}
  18. {$SETC UsingIncludes := 0}
  19. {$ENDC}
  20.  
  21. {$IFC NOT UsingIncludes}
  22.  UNIT AppleGuide;
  23.  INTERFACE
  24. {$ENDC}
  25.  
  26. {$IFC UNDEFINED __APPLEGUIDE__}
  27. {$SETC __APPLEGUIDE__ := 1}
  28.  
  29. {$I+}
  30. {$SETC AppleGuideIncludes := UsingIncludes}
  31. {$SETC UsingIncludes := 1}
  32.  
  33. {$IFC UNDEFINED __TYPES__}
  34. {$I Types.p}
  35. {$ENDC}
  36. {$IFC UNDEFINED __APPLEEVENTS__}
  37. {$I AppleEvents.p}
  38. {$ENDC}
  39. {$IFC UNDEFINED __FILES__}
  40. {$I Files.p}
  41. {$ENDC}
  42.  
  43.  
  44.  
  45. {$PUSH}
  46. {$ALIGN MAC68K}
  47. {$LibExport+}
  48.  
  49. {  Types }
  50.  
  51. TYPE
  52.     AGRefNum                            = UInt32;
  53.     AGCoachRefNum                        = UInt32;
  54.     AGContextRefNum                        = UInt32;
  55.     AGAppInfoPtr = ^AGAppInfo;
  56.     AGAppInfo = RECORD
  57.         eventId:                AEEventID;
  58.         refCon:                    LONGINT;
  59.         contextObj:                Ptr;                                    {  private system field }
  60.     END;
  61.  
  62.     AGAppInfoHdl                        = ^AGAppInfoPtr;
  63. {$IFC TYPED_FUNCTION_POINTERS}
  64.     CoachReplyProcPtr = FUNCTION(VAR pRect: Rect; name: Ptr; refCon: LONGINT): OSErr;
  65. {$ELSEC}
  66.     CoachReplyProcPtr = ProcPtr;
  67. {$ENDC}
  68.  
  69. {$IFC TYPED_FUNCTION_POINTERS}
  70.     ContextReplyProcPtr = FUNCTION(pInputData: Ptr; inputDataSize: Size; VAR ppOutputData: Ptr; VAR pOutputDataSize: Size; hAppInfo: AGAppInfoHdl): OSErr;
  71. {$ELSEC}
  72.     ContextReplyProcPtr = ProcPtr;
  73. {$ENDC}
  74.  
  75.     CoachReplyUPP = UniversalProcPtr;
  76.     ContextReplyUPP = UniversalProcPtr;
  77.  
  78. CONST
  79.     uppCoachReplyProcInfo = $00000FE0;
  80.     uppContextReplyProcInfo = $0000FFE0;
  81.  
  82. FUNCTION NewCoachReplyProc(userRoutine: CoachReplyProcPtr): CoachReplyUPP;
  83.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  84.     INLINE $2E9F;
  85.     {$ENDC}
  86.  
  87. FUNCTION NewContextReplyProc(userRoutine: ContextReplyProcPtr): ContextReplyUPP;
  88.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  89.     INLINE $2E9F;
  90.     {$ENDC}
  91.  
  92. FUNCTION CallCoachReplyProc(VAR pRect: Rect; name: Ptr; refCon: LONGINT; userRoutine: CoachReplyUPP): OSErr;
  93.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  94.     INLINE $205F, $4E90;
  95.     {$ENDC}
  96.  
  97. FUNCTION CallContextReplyProc(pInputData: Ptr; inputDataSize: Size; VAR ppOutputData: Ptr; VAR pOutputDataSize: Size; hAppInfo: AGAppInfoHdl; userRoutine: ContextReplyUPP): OSErr;
  98.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  99.     INLINE $205F, $4E90;
  100.     {$ENDC}
  101. {  Constants }
  102.  
  103.  
  104.  
  105. CONST
  106.     kAGDefault                    = 0;
  107.     kAGFrontDatabase            = 1;
  108.     kAGNoMixin                    = -1;
  109.  
  110.  
  111.     kAGViewFullHowdy            = 1;                            {  Full-size Howdy }
  112.     kAGViewTopicAreas            = 2;                            {  Full-size Topic Areas }
  113.     kAGViewIndex                = 3;                            {  Full-size Index Terms }
  114.     kAGViewLookFor                = 4;                            {  Full-size Look-For (Search) }
  115.     kAGViewSingleHowdy            = 5;                            {  Single-list-size Howdy }
  116.     kAGViewSingleTopics            = 6;                            {  Single-list-size Topics }
  117.  
  118.  
  119.     kAGFileMain                    = 'poco';
  120.     kAGFileMixin                = 'mixn';
  121.  
  122. {  To test against AGGetAvailableDBTypes }
  123.     kAGDBTypeBitAny                = $00000001;
  124.     kAGDBTypeBitHelp            = $00000002;
  125.     kAGDBTypeBitTutorial        = $00000004;
  126.     kAGDBTypeBitShortcuts        = $00000008;
  127.     kAGDBTypeBitAbout            = $00000010;
  128.     kAGDBTypeBitOther            = $00000080;
  129.  
  130.  
  131.  
  132. TYPE
  133.     AGStatus                            = UInt16;
  134. {  Returned by AGGetStatus }
  135.  
  136. CONST
  137.     kAGIsNotRunning                = 0;
  138.     kAGIsSleeping                = 1;
  139.     kAGIsActive                    = 2;
  140.  
  141. {  Flags used in AGOpen, AGOpenWithSearch, AGOpenWithView }
  142.     kHelpViewerSearchAll        = $01;
  143.  
  144.  
  145. TYPE
  146.     AGWindowKind                        = UInt16;
  147. {  Returned by AGGetFrontWindowKind }
  148.  
  149. CONST
  150.     kAGNoWindow                    = 0;
  151.     kAGAccessWindow                = 1;
  152.     kAGPresentationWindow        = 2;
  153.  
  154. {  Error Codes }
  155.  
  156. {  Not an enum, because other OSErrs are valid. }
  157.  
  158. TYPE
  159.     AGErr                                = SInt16;
  160. {  Apple Guide error codes }
  161.  
  162. CONST
  163.                                                                 {  -------------------- Apple event reply codes }
  164.     kAGErrUnknownEvent            = -2900;
  165.     kAGErrCantStartup            = -2901;
  166.     kAGErrNoAccWin                = -2902;
  167.     kAGErrNoPreWin                = -2903;
  168.     kAGErrNoSequence            = -2904;
  169.     kAGErrNotOopsSequence        = -2905;
  170.     kAGErrReserved06            = -2906;
  171.     kAGErrNoPanel                = -2907;
  172.     kAGErrContentNotFound        = -2908;
  173.     kAGErrMissingString            = -2909;
  174.     kAGErrInfoNotAvail            = -2910;
  175.     kAGErrEventNotAvailable        = -2911;
  176.     kAGErrCannotMakeCoach        = -2912;
  177.     kAGErrSessionIDsNotMatch    = -2913;
  178.     kAGErrMissingDatabaseSpec    = -2914;
  179.     kAGMissingSequenceMap        = -2915;                        {  -------------------- Coach's Chalkboard reply codes }
  180.     kAGErrItemNotFound            = -2925;
  181.     kAGErrBalloonResourceNotFound = -2926;
  182.     kAGErrChalkResourceNotFound    = -2927;
  183.     kAGErrChdvResourceNotFound    = -2928;
  184.     kAGErrAlreadyShowing        = -2929;
  185.     kAGErrBalloonResourceSkip    = -2930;
  186.     kAGErrItemNotVisible        = -2931;
  187.     kAGErrReserved32            = -2932;
  188.     kAGErrNotFrontProcess        = -2933;
  189.     kAGErrMacroResourceNotFound    = -2934;                        {  -------------------- API reply codes }
  190.     kAGErrAppleGuideNotAvailable = -2951;
  191.     kAGErrCannotInitCoach        = -2952;
  192.     kAGErrCannotInitContext        = -2953;
  193.     kAGErrCannotOpenAliasFile    = -2954;
  194.     kAGErrNoAliasResource        = -2955;
  195.     kAGErrDatabaseNotAvailable    = -2956;
  196.     kAGErrDatabaseNotOpen        = -2957;
  197.     kAGErrMissingAppInfoHdl        = -2958;
  198.     kAGErrMissingContextObject    = -2959;
  199.     kAGErrInvalidRefNum            = -2960;
  200.     kAGErrDatabaseOpen            = -2961;
  201.     kAGErrInsufficientMemory    = -2962;
  202.  
  203. {  Events }
  204.  
  205. {  Not an enum because we want to make assignments. }
  206.  
  207. TYPE
  208.     AGEvent                                = UInt32;
  209. {  Handy events for AGGeneral. }
  210.  
  211. CONST
  212.                                                                 {  Panel actions (Require a presentation window). }
  213.     kAGEventDoCoach                = 'doco';
  214.     kAGEventDoHuh                = 'dhuh';
  215.     kAGEventGoNext                = 'gonp';
  216.     kAGEventGoPrev                = 'gopp';
  217.     kAGEventHidePanel            = 'pahi';
  218.     kAGEventReturnBack            = 'gobk';
  219.     kAGEventShowPanel            = 'pash';
  220.     kAGEventTogglePanel            = 'patg';
  221.  
  222. {  Functions }
  223.  
  224. {
  225.    AGClose
  226.    Close the database associated with the AGRefNum.
  227. }
  228.  
  229. FUNCTION AGClose(VAR refNum: AGRefNum): AGErr;
  230.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  231.     INLINE $7011, $AA6E;
  232.     {$ENDC}
  233. {
  234.    AGGeneral
  235.    Cause various events to happen.
  236. }
  237.  
  238. FUNCTION AGGeneral(refNum: AGRefNum; theEvent: AGEvent): AGErr;
  239.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  240.     INLINE $700D, $AA6E;
  241.     {$ENDC}
  242. {
  243.    AGGetAvailableDBTypes
  244.    Return the database types available for this application.
  245. }
  246.  
  247. FUNCTION AGGetAvailableDBTypes: UInt32;
  248.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  249.     INLINE $7008, $AA6E;
  250.     {$ENDC}
  251. {
  252.    AGGetFrontWindowKind
  253.    Return the kind of the front window.
  254. }
  255.  
  256. FUNCTION AGGetFrontWindowKind(refNum: AGRefNum): AGWindowKind;
  257.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  258.     INLINE $700C, $AA6E;
  259.     {$ENDC}
  260. {
  261.    AGGetFSSpec
  262.    Return the FSSpec for the AGRefNum.
  263. }
  264.  
  265. FUNCTION AGGetFSSpec(refNum: AGRefNum; VAR fileSpec: FSSpec): AGErr;
  266.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  267.     INLINE $700F, $AA6E;
  268.     {$ENDC}
  269. {
  270.    AGGetStatus
  271.    Return the status of Apple Guide.
  272. }
  273.  
  274. FUNCTION AGGetStatus: AGStatus;
  275.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  276.     INLINE $7009, $AA6E;
  277.     {$ENDC}
  278. {
  279.    AGInstallCoachHandler
  280.    Install a Coach object location query handler.
  281. }
  282.  
  283. FUNCTION AGInstallCoachHandler(coachReplyProc: CoachReplyUPP; refCon: LONGINT; VAR resultRefNum: AGCoachRefNum): AGErr;
  284.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  285.     INLINE $7012, $AA6E;
  286.     {$ENDC}
  287. {
  288.    AGInstallContextHandler
  289.    Install a context check query handler.
  290. }
  291.  
  292. FUNCTION AGInstallContextHandler(contextReplyProc: ContextReplyUPP; eventID: AEEventID; refCon: LONGINT; VAR resultRefNum: AGContextRefNum): AGErr;
  293.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  294.     INLINE $7013, $AA6E;
  295.     {$ENDC}
  296. {
  297.    AGIsDatabaseOpen
  298.    Return true if the database associated with the AGRefNum is open.
  299. }
  300.  
  301. FUNCTION AGIsDatabaseOpen(refNum: AGRefNum): BOOLEAN;
  302.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  303.     INLINE $7006, $AA6E;
  304.     {$ENDC}
  305. {
  306.    AGOpen
  307.    Open a guide database.
  308. }
  309.  
  310. FUNCTION AGOpen(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; VAR resultRefNum: AGRefNum): AGErr;
  311.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  312.     INLINE $7001, $AA6E;
  313.     {$ENDC}
  314. {
  315.    AGOpenWithSearch
  316.    Open a guide database and preset a search string.
  317. }
  318.  
  319. FUNCTION AGOpenWithSearch(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; searchString: Str255; VAR resultRefNum: AGRefNum): AGErr;
  320.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  321.     INLINE $7002, $AA6E;
  322.     {$ENDC}
  323. {
  324.    AGOpenWithSequence
  325.    Open a guide database and display a presentation window sequence.
  326. }
  327.  
  328. FUNCTION AGOpenWithSequence(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; sequenceID: INTEGER; VAR resultRefNum: AGRefNum): AGErr;
  329.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  330.     INLINE $7004, $AA6E;
  331.     {$ENDC}
  332. {
  333.    AGOpenWithView
  334.    Open a guide database and override the default view.
  335. }
  336.  
  337. FUNCTION AGOpenWithView(fileSpec: ConstFSSpecPtr; flags: UInt32; mixinControl: Handle; viewNum: INTEGER; VAR resultRefNum: AGRefNum): AGErr;
  338.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  339.     INLINE $7005, $AA6E;
  340.     {$ENDC}
  341. {
  342.    AGQuit
  343.    Make Apple Guide quit.
  344. }
  345.  
  346. FUNCTION AGQuit: AGErr;
  347.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  348.     INLINE $7010, $AA6E;
  349.     {$ENDC}
  350. {
  351.    AGRemoveCoachHandler
  352.    Remove the Coach object location query handler.
  353. }
  354.  
  355. FUNCTION AGRemoveCoachHandler(VAR resultRefNum: AGCoachRefNum): AGErr;
  356.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  357.     INLINE $7014, $AA6E;
  358.     {$ENDC}
  359. {
  360.    AGRemoveContextHandler
  361.    Remove the context check query handler.
  362. }
  363.  
  364. FUNCTION AGRemoveContextHandler(VAR resultRefNum: AGContextRefNum): AGErr;
  365.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  366.     INLINE $7015, $AA6E;
  367.     {$ENDC}
  368. {
  369.    AGStart
  370.    Start up Apple Guide in the background.
  371. }
  372.  
  373. FUNCTION AGStart: AGErr;
  374.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  375.     INLINE $700A, $AA6E;
  376.     {$ENDC}
  377.  
  378.  
  379. {  typedef's }
  380.  
  381.  
  382. TYPE
  383.     AGFileFSSpecType                    = FSSpec;
  384.     AGFileFSSpecTypePtr                 = ^AGFileFSSpecType;
  385.     AGFileSelectorCountType                = INTEGER;
  386.     AGFileSelectorIndexType                = INTEGER;
  387.     AGFileSelectorType                    = OSType;
  388.     AGFileSelectorValueType                = LONGINT;
  389.     AGFileDBType                        = INTEGER;
  390.     AGFileDBMenuNamePtr                    = Str63;
  391.     AGFileDBScriptType                    = INTEGER;
  392.     AGFileDBRegionType                    = INTEGER;
  393.     AGFileMajorRevType                    = INTEGER;
  394.     AGFileMinorRevType                    = INTEGER;
  395.     AGFileCountType                        = INTEGER;
  396. {  Database types (for AGFileDBType parameter). }
  397.  
  398. CONST
  399.     kAGFileDBTypeAny            = 0;
  400.     kAGFileDBTypeHelp            = 1;
  401.     kAGFileDBTypeTutorial        = 2;
  402.     kAGFileDBTypeShortcuts        = 3;
  403.     kAGFileDBTypeAbout            = 4;
  404.     kAGFileDBTypeOther            = 8;
  405.  
  406.  
  407.  
  408. FUNCTION AGFileGetDBMenuName({CONST}VAR fileSpec: FSSpec; VAR menuItemNameString: Str63): OSErr;
  409. {  Get the database type. }
  410. FUNCTION AGFileGetDBType({CONST}VAR fileSpec: FSSpec; VAR databaseType: AGFileDBType): OSErr;
  411. {
  412.    Get the version of the software
  413.    that created this database.
  414. }
  415. FUNCTION AGFileGetDBVersion({CONST}VAR fileSpec: FSSpec; VAR majorRev: AGFileMajorRevType; VAR minorRev: AGFileMinorRevType): OSErr;
  416. {  Get the database script and region information. }
  417. FUNCTION AGFileGetDBCountry({CONST}VAR fileSpec: FSSpec; VAR script: AGFileDBScriptType; VAR region: AGFileDBRegionType): OSErr;
  418. {  Return the number of selectors in database. }
  419. FUNCTION AGFileGetSelectorCount({CONST}VAR fileSpec: FSSpec): AGFileSelectorCountType;
  420. {
  421.    Get the i-th database selector (1 to AGFileSelectorCountType)
  422.    and its value.
  423. }
  424. FUNCTION AGFileGetSelector({CONST}VAR fileSpec: FSSpec; selectorNumber: AGFileSelectorIndexType; VAR selector: AGFileSelectorType; VAR value: AGFileSelectorValueType): OSErr;
  425. {  Return true if database is mixin. }
  426. FUNCTION AGFileIsMixin({CONST}VAR fileSpec: FSSpec): BOOLEAN;
  427. {
  428.    Return the number of database files
  429.    of the specified databaseType and main/mixin.
  430.    Any file creator is acceptible,
  431.    but type must be kAGFileMain or kAGFileMixin.
  432. }
  433. FUNCTION AGFileGetDBCount(vRefNum: INTEGER; dirID: LONGINT; databaseType: AGFileDBType; wantMixin: BOOLEAN): AGFileCountType;
  434. {
  435.    Get the FSSpec for the dbIndex-th database
  436.    of the specified databaseType and main/mixin.
  437.    Any file creator is acceptible,
  438.    but type must be kAGFileMain or kAGFileMixin.
  439. }
  440. FUNCTION AGFileGetIndDB(vRefNum: INTEGER; dirID: LONGINT; databaseType: AGFileDBType; wantMixin: BOOLEAN; dbIndex: INTEGER; VAR fileSpec: FSSpec): OSErr;
  441. {
  442.    This selector must match with the application
  443.    creator in order for this file to appear in the 
  444.    application's Help menu. Ignored for mixin files
  445.    because they never appear in the Help menu anyway.
  446.    If empty (zeros), will appear in the Help menu
  447.    of any host application.
  448. }
  449. FUNCTION AGFileGetHelpMenuAppCreator({CONST}VAR fileSpec: FSSpec; VAR helpMenuAppCreator: OSType): OSErr;
  450. {
  451.    This selector must match in the main and mixin
  452.    files in order for the mixin to mix-in with the main.
  453.    Empty (zeros) selectors are valid matches.
  454.    A '****' selector will mix-in with any main.
  455. }
  456. FUNCTION AGFileGetMixinMatchSelector({CONST}VAR fileSpec: FSSpec; VAR mixinMatchSelector: OSType): OSErr;
  457. {
  458.    This is the text of the balloon for the
  459.    Help menu item for this database.
  460. }
  461. FUNCTION AGFileGetHelpMenuBalloonText({CONST}VAR fileSpec: FSSpec; VAR helpMenuBalloonString: Str255): OSErr;
  462.  
  463. FUNCTION AGGetSystemDB(databaseType: AGFileDBType; wantMixin: BOOLEAN; VAR pFileSpec: FSSpec): OSErr;
  464. {$ALIGN RESET}
  465. {$POP}
  466.  
  467. {$SETC UsingIncludes := AppleGuideIncludes}
  468.  
  469. {$ENDC} {__APPLEGUIDE__}
  470.  
  471. {$IFC NOT UsingIncludes}
  472.  END.
  473. {$ENDC}
  474.